Prepare ml4t-models 0.1.0 stable release - #29
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR prepares ml4t-models for the 0.1.0 stable release by formalizing the supported public API, tightening validation/persistence/observability contracts, and adding CI/release gating to ensure a single immutable release-candidate artifact is qualified across required environments before publication.
Changes:
- Freezes the stable export surface (
__all__manifests, stable submodule exports) and expands contract tests for batch/result types, dtype semantics, and estimator validation. - Adds fit observability + persistence/load/save support across model families, plus improved device/dtype resolution and deterministic CUDA seeding behavior.
- Introduces release-candidate tooling (candidate manifest, wheel comparison, coverage/performance checks) and new CI/release workflows + repo hygiene gates + packaging/docs updates.
Reviewed changes
Copilot reviewed 106 out of 108 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_types.py | Adds shape/identity/timestamp alignment and contract tests for batch/result dataclasses. |
| tests/test_torch_runtime.py | Expands device/dtype resolution and deterministic seeding tests. |
| tests/test_stochastic_discount_factor.py | Updates SDF config validation expectation; removes torch import skip. |
| tests/test_sae.py | Removes torch import skip to run under deep test environments. |
| tests/test_rp_pca.py | Adds checkpoint rejection test for RP-PCA extraction. |
| tests/test_repo_hygiene.py | Adds repository/workflow/security policy hygiene gates. |
| tests/test_release_candidate.py | Adds candidate manifest + wheel reproducibility + perf/hardware gate tests. |
| tests/test_public_api.py | Validates stable root and submodule exports against authoritative manifest. |
| tests/test_portfolio.py | Adds neural portfolio quickstart + topology reuse/rejection tests. |
| tests/test_pca_pipeline.py | Adds asset reorder and redaction tests; checkpoint rejection tests. |
| tests/test_observability.py | Adds fit run record stability/redaction and failure-record behavior tests. |
| tests/test_neural_components.py | Adds unit tests for internal torch network components. |
| tests/test_latent_factor_utils.py | Adds coverage for latent-factor utility functions and edge cases. |
| tests/test_ipca.py | Adds checkpoint rejection test for IPCA extraction. |
| tests/test_ipca_normalization.py | Updates IPCA sign convention test to match new normalization semantics. |
| tests/test_integration_surfaces.py | Adds ResultsFrame export tests and atomic backtest artifact writing tests. |
| tests/test_integration_data.py | Adds schema coercion/dup detection/nonfinite handling/identity preservation tests. |
| tests/test_integration_backtest.py | Strengthens feed spec mapping + backtest inputs validation and fallback behavior. |
| tests/test_forecasters.py | Adds “predict/save before fit” rejection tests. |
| tests/test_examples.py | Removes conditional torch skipping for example execution. |
| tests/test_estimator_validation.py | Adds explicit estimator validation tests for finite info and factor history. |
| tests/test_dtype_semantics.py | Adds dtype propagation + run record assertions across estimators. |
| tests/test_coverage_gate.py | Adds tests for coverage threshold enforcement script. |
| tests/test_core_install.py | Ensures core workflows run without torch and deep imports fail with guidance. |
| tests/test_configs.py | Adds broad config validation tests and “identity not overridable” checks. |
| tests/test_cae.py | Removes importorskip and uses torch directly for CAE tests. |
| src/ml4t/models/stochastic_discount_factor/base.py | Adds FitObservable integration for SDF base model. |
| src/ml4t/models/stochastic_discount_factor/init.py | Removes base class from public stochastic_discount_factor exports. |
| src/ml4t/models/py.typed | Adds PEP 561 marker for typed package distribution. |
| src/ml4t/models/portfolio/postprocessors.py | Reworks cross-sectional weight normalization to enforce feasibility and constraints. |
| src/ml4t/models/portfolio/lstm.py | Adds observability, dtype/device resolution, atomic fit lifecycle, and persistence. |
| src/ml4t/models/portfolio/losses.py | Improves masking, adds turnover penalty support, stabilizes softmin Sharpe. |
| src/ml4t/models/portfolio/linear.py | Adds observability, dtype support, and persistence/load/save for linear portfolio model. |
| src/ml4t/models/portfolio/components.py | Fixes config import path to portfolio config module. |
| src/ml4t/models/portfolio/base.py | Adds FitObservable to portfolio base model. |
| src/ml4t/models/portfolio/init.py | Removes internal exports and adds friendly torch-missing ImportError on lazy imports. |
| src/ml4t/models/mappers/beta_lambda.py | Improves shape mismatch error messages with expected vs got. |
| src/ml4t/models/mappers/base.py | Updates mapper config import path. |
| src/ml4t/models/mappers/init.py | Removes base mapper from exports; keeps supported mapper(s). |
| src/ml4t/models/latent_factors/rp_pca.py | Adds dtype support, asset order resolution, and persistence/load/save. |
| src/ml4t/models/latent_factors/pca.py | Adds dtype + stronger validation, asset order resolution, and persistence/load/save. |
| src/ml4t/models/latent_factors/ipca.py | Adds dtype + checkpoint validation, and persistence/load/save. |
| src/ml4t/models/latent_factors/base.py | Adds FitObservable and updates latent factor config import path. |
| src/ml4t/models/latent_factors/init.py | Removes base latent factor model from exports. |
| src/ml4t/models/integration/surfaces.py | Implements atomic generation publishing and manifesting for artifacts. |
| src/ml4t/models/integration/data.py | Changes cross-section long-frame ingestion to stable asset identity + dup detection. |
| src/ml4t/models/integration/backtest.py | Expands fallback feed spec mapping support for additional fields. |
| src/ml4t/models/forecasters/mean.py | Adds fit observability, dtype handling, validation helper, and persistence. |
| src/ml4t/models/forecasters/ewma.py | Adds fit observability, improved finite-handling, dtype, and persistence. |
| src/ml4t/models/forecasters/base.py | Adds FitObservable and shared factor-return validation helper. |
| src/ml4t/models/forecasters/ar.py | Adds fit observability, dtype handling, finite checks, and persistence. |
| src/ml4t/models/forecasters/init.py | Removes base forecaster from exports; keeps supported concrete forecasters. |
| src/ml4t/models/configs/portfolio.py | Freezes model identity via ClassVar, strengthens validation, adjusts defaults. |
| src/ml4t/models/configs/pipeline.py | Removes PipelineConfig from public config surface. |
| src/ml4t/models/configs/latent_factor.py | Freezes identity via ClassVar and adds extensive validation/post-init checks. |
| src/ml4t/models/configs/forecast.py | Freezes identity via ClassVar and validates EWMA half-life. |
| src/ml4t/models/configs/base.py | Adds shared validation helpers and validates seed/device/dtype. |
| src/ml4t/models/configs/asset_prediction.py | Freezes identity via ClassVar and adds SAE config validation. |
| src/ml4t/models/configs/init.py | Tightens exported config surface to supported stable configs. |
| src/ml4t/models/asset_prediction/sae.py | Adds observability, dtype support, atomic fit, and persistence/load/save. |
| src/ml4t/models/asset_prediction/base.py | Adds FitObservable and narrows config import path. |
| src/ml4t/models/asset_prediction/init.py | Narrows exports to supported SAEModel only. |
| src/ml4t/models/api.py | Adds stable all and extends protocols with checkpoints + fit records. |
| src/ml4t/models/_version.py | Centralizes package version for runtime metadata. |
| src/ml4t/models/_public_api.py | Introduces authoritative stable root export manifest. |
| src/ml4t/models/_internal/torch_runtime.py | Adds dtype resolver, stricter device resolution, and deterministic CUDA settings. |
| src/ml4t/models/_internal/stochastic_discount_factor_nn.py | Fixes dtype propagation + masking and adjusts SDF construction sign. |
| src/ml4t/models/_internal/portfolio_validation.py | Adds tensor-independent validation helpers for portfolio batches. |
| src/ml4t/models/_internal/observability.py | Adds fit run recording with redaction and input hashing. |
| src/ml4t/models/_internal/lifecycle.py | Adds atomic fit attribute rollback decorator. |
| src/ml4t/models/_internal/latent_factor_utils.py | Updates managed portfolio computation and improves rank-correlation robustness. |
| src/ml4t/models/init.py | Switches to centralized version, updates exports, and improves torch-missing errors. |
| SECURITY.md | Adds a security policy with supported versions and private reporting route. |
| scripts/ci/test_wheel.py | Adds installed-wheel validation for core/full modes and consumer typecheck check. |
| scripts/ci/check_performance.py | Adds performance record + replay drift verification utility. |
| scripts/ci/check_coverage.py | Adds line/branch coverage enforcement utility and thresholds. |
| scripts/ci/candidate.py | Adds release-candidate manifest creation/verification and wheel comparison. |
| README.md | Updates install guidance, supported Python versions, and formatting. |
| pyproject.toml | Updates versioning source, packaging inclusions, dependencies, and pytest coverage config. |
| mkdocs.yml | Adds revision/version markers to published docs via environment variables. |
| docs/user-guide/stochastic-discount-factor.md | Reformats imports to match style and stable docs presentation. |
| docs/reference/release-gates.md | Updates release gate documentation to match new CI workflows and scripts. |
| docs/overrides/partials/footer.html | Adds release version/commit display in docs footer. |
| docs/getting-started/quickstart.md | Formatting tweaks and updated import style. |
| docs/getting-started/installation.md | Updates docs tool instructions and clarifies “all” extra semantics. |
| docs/book-guide/index.md | Updates stable line language from beta to 0.1.0 stable. |
| .pre-commit-config.yaml | Adds local pre-commit hooks for Ruff/ty/pytest. |
| .gitignore | Stops ignoring _version.py and updates ignored artifacts list. |
| .github/workflows/docs.yml | Removes standalone docs workflow (superseded by CI/release workflow gating). |
| .github/actionlint.yaml | Adds self-hosted runner label configuration for actionlint. |
| .gitattributes | Enforces LF line endings for platform-independent text files. |
| .github/workflows/ci.yml | Adds full multi-platform candidate build/verification/qualification workflow. |
| .github/workflows/release.yml | Adds release workflow that promotes qualified artifacts without rebuilding. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+49
to
+54
| action_references = [ | ||
| line.strip() | ||
| for workflow in workflows | ||
| for line in workflow.read_text(encoding="utf-8").splitlines() | ||
| if "uses:" in line | ||
| ] |
Comment on lines
+70
to
+73
| assert "os: [ubuntu-latest, macos-latest, windows-latest]" in workflow | ||
| assert 'python-version: ["3.12", "3.13", "3.14"]' in workflow | ||
| assert 'python-version: "3.15"' in workflow | ||
| assert "allow-prereleases: true" in workflow |
Comment on lines
+150
to
+154
| def _update_array_digest(digest: Any, array: np.ndarray) -> None: | ||
| digest.update(array.dtype.str.encode()) | ||
| digest.update(repr(array.shape).encode()) | ||
| iterator = np.nditer( | ||
| array, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Why
The stable-readiness audit found 44 issues, including 39 release blockers. This change closes the code and local-evidence findings and moves the remaining operating-system, Python, CUDA, performance, release, and deployment evidence into enforceable GitHub workflows.
Impact
This prepares
ml4t-models0.1.0 for a stable release. It tightens validation and persistence behavior, makes public errors actionable, and requires one immutable candidate artifact to pass the release gates before publication.Validation
The PR remains draft until the supported GitHub-hosted matrix and protected remote release workflow have passed.